메시지 블록 처리하기

Claude의 도구 기능을 사용할 때, 이전에 보던 단순한 텍스트 응답과는 다른 새로운 응답 구조를 접하게 됩니다. 단일 텍스트 블록만 반환하는 것이 아니라, Claude는 이제 텍스트와 도구 사용 정보를 모두 포함하는 멀티 블록 메시지를 반환할 수 있습니다.

도구를 활성화한 API 호출하기

Claude가 도구를 사용할 수 있도록 하려면 API 호출에 tools 파라미터를 포함해야 합니다. 요청 구조는 다음과 같습니다:

messages = []
messages.append({
    "role": "user",
    "content": "What is the exact time, formatted as HH:MM:SS?"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],
)

tools 파라미터는 Claude가 호출할 수 있는 함수를 설명하는 JSON 스키마 목록을 받습니다.

멀티 블록 메시지 이해하기

Claude가 도구를 사용하기로 결정하면, 콘텐츠 목록에 여러 블록이 포함된 어시스턴트 메시지를 반환합니다. 이는 이전에 다루던 단순한 텍스트 전용 응답과 크게 다른 점입니다.

멀티 블록 메시지는 일반적으로 다음을 포함합니다:

텍스트 블록 - Claude가 수행하는 작업을 설명하는 사람이 읽을 수 있는 텍스트 (예: "현재 시간을 찾아드리겠습니다. 잠시만 기다려 주세요")
ToolUse 블록 - 어떤 도구를 호출하고 어떤 파라미터를 사용할지 코드에 전달하는 지침

ToolUse 블록에는 다음이 포함됩니다:

도구 호출을 추적하기 위한 ID
호출할 함수의 이름 (예: "get_current_datetime")
딕셔너리 형식으로 지정된 입력 파라미터
"tool_use" 타입 지정자

멀티 블록 메시지로 대화 기록 관리하기

Claude는 대화 기록을 저장하지 않으므로 직접 관리해야 합니다. 도구 응답을 처리할 때는 모든 블록을 포함한 전체 콘텐츠 구조를 보존해야 합니다.

멀티 블록 어시스턴트 메시지를 대화 기록에 올바르게 추가하는 방법은 다음과 같습니다:

messages.append({
    "role": "assistant",
    "content": response.content
})

이렇게 하면 텍스트 블록과 도구 사용 블록이 모두 보존되며, 이후 API 호출 시 대화 컨텍스트를 유지하는 데 매우 중요합니다.

전체 도구 사용 흐름

도구 사용 과정은 다음 패턴을 따릅니다:

도구 스키마와 함께 사용자 메시지를 Claude에 전송
텍스트 블록과 도구 사용 블록이 포함된 어시스턴트 메시지 수신
도구 정보를 추출하고 실제 함수 실행
전체 대화 기록과 함께 도구 결과를 Claude에 다시 전송
Claude로부터 최종 응답 수신

각 단계에서는 Claude가 정확한 응답을 제공하는 데 필요한 전체 컨텍스트를 확보할 수 있도록 메시지 구조를 신중하게 처리해야 합니다.

헬퍼 함수 업데이트하기

add_user_message()와 add_assistant_message() 같은 헬퍼 함수를 사용해 왔다면, 멀티 블록 콘텐츠를 처리할 수 있도록 업데이트해야 합니다. 현재 버전은 단일 텍스트 블록만 지원할 가능성이 높지만, 이제 도구 사용 블록을 포함하는 더 복잡한 콘텐츠 구조도 수용할 수 있어야 합니다.

이 멀티 블록 메시지 처리는 올바른 대화 흐름을 유지하면서 Claude의 도구 기능을 원활하게 통합하는 견고한 애플리케이션을 구축하는 데 필수적입니다.